03.a - GitHub-OAuth-Initiation | DeepWiki

Relevant source files

CLAUDE.md

app/api/auth/github/route.ts

app/success/RedirectTimer.tsx

app/success/page.tsx

Purpose and ScopeLink copied!

This page documents the /api/auth/github endpoint, which initiates the GitHub OAuth and App installation flow. This endpoint is responsible for generating secure state parameters, embedding the Stripe session_id for payment correlation, storing CSRF protection cookies, and redirecting users to the GitHub App installation page.

For details on what happens after GitHub redirects back to the application, see OAuth Callback Handler. For information about the GitHub App installation process itself, see GitHub App Installation Flow.

Endpoint OverviewLink copied!

The OAuth initiation endpoint is implemented as a GET route handler at /api/auth/github and serves as the entry point for connecting a user's GitHub account after payment completion.

Route Location and Entry PointLink copied!

Attribute	Value
File Path	`app/api/auth/github/route.ts`
HTTP Method	GET
Route Pattern	`/api/auth/github`
Query Parameters	`session_id` (optional, passed from success page)
Return Type	HTTP 302 Redirect to GitHub

The endpoint is invoked when users click the "Connect GitHub" button on the success page app/success/page.tsx L54

Request Flow Diagram

Sources: app/api/auth/github/route.ts L1-L44

app/success/page.tsx L54-L59

State Parameter Generation and Session ID EmbeddingLink copied!

The endpoint generates a state parameter that serves two purposes: CSRF protection and payment-to-installation correlation. This state encodes both a random UUID and the Stripe session_id.

State Data StructureLink copied!

The state generation logic app/api/auth/github/route.ts L16-L20

Field	Purpose	Source
`uuid`	CSRF protection token (random)	`crypto.randomUUID()`
`sessionId`	Links payment to installation	Query parameter from success page
Encoding	URL-safe transmission	Base64 encoding of JSON string

Implementation DetailsLink copied!

The endpoint extracts the session_id from the query string app/api/auth/github/route.ts L12-L13

and constructs a state object containing both the CSRF token and session identifier. This state is then Base64-encoded app/api/auth/github/route.ts L20

to create a URL-safe string that GitHub will return unchanged in the callback.

Console Logging: The endpoint logs the state generation process at three stages app/api/auth/github/route.ts L22-L24

Original session_id value
Decoded stateData object structure
Final encoded state string

These logs are critical for debugging payment-to-installation correlation issues in Vercel logs.

Sources: app/api/auth/github/route.ts L11-L24

CSRF Protection via CookiesLink copied!

The generated state parameter is stored in an HTTP-only cookie to enable server-side verification during the OAuth callback. This prevents CSRF attacks where malicious sites attempt to complete OAuth flows with attacker-controlled state values.

The cookie is configured with the following security attributes app/api/auth/github/route.ts L29-L34

Attribute	Value	Security Purpose
`path`	`/`	Cookie available to all routes
`secure`	`true` in production	Prevents transmission over HTTP
`httpOnly`	`true`	Prevents JavaScript access (XSS mitigation)
`maxAge`	3600 seconds (1 hour)	Limits exposure window for stolen cookies

The cookie name github_oauth_state app/api/auth/github/route.ts L29

is referenced by the callback handler to retrieve and validate the state parameter. This name must match the retrieval logic in /api/auth/github/callback.

Sources: app/api/auth/github/route.ts L26-L34

GitHub App Installation RedirectLink copied!

After generating and storing the state parameter, the endpoint constructs a redirect URL to the GitHub App installation page.

Redirect URL ConstructionLink copied!

Configuration RequirementsLink copied!

The endpoint requires the GITHUB_APP_SLUG environment variable app/api/auth/github/route.ts L5

to construct the installation URL. If this variable is missing, the endpoint returns a 500 error app/api/auth/github/route.ts L7-L9

Component	Example Value	Description
Base URL	`https://github.com/apps/`	GitHub's app installation base path
App Slug	`godeep-wiki-integration`	Your GitHub App's unique identifier
Path	`/installations/new`	Triggers new installation flow
Query Param	`?state=eyJ1dWlkIjoi...`	Passes encoded state back to callback

Redirect BehaviorLink copied!

The endpoint uses Next.js's redirect() function app/api/auth/github/route.ts L43

to issue an HTTP 302 redirect. This is a server-side redirect that occurs before any response is sent to the client.

When users land on the GitHub installation page, they will:

See the GitHub App's permission requests
Select which repositories to grant access to
Complete the installation, triggering GitHub to redirect back to the callback URL configured in the GitHub App settings

Sources: app/api/auth/github/route.ts L5-L44

Security ConsiderationsLink copied!

The OAuth initiation endpoint implements multiple security layers to protect against common web vulnerabilities.

Threat Mitigation SummaryLink copied!

Threat	Mitigation	Implementation
CSRF Attacks	Random UUID in state + cookie verification	`crypto.randomUUID()` app/api/auth/github/route.ts L17
XSS Token Theft	HTTP-only cookies	`httpOnly: true` app/api/auth/github/route.ts L32
Man-in-the-Middle	HTTPS enforcement in production	`secure: true` (production) app/api/auth/github/route.ts L31
Session Hijacking	Short cookie lifespan	`maxAge: 3600` (1 hour) app/api/auth/github/route.ts L33
Replay Attacks	One-time state parameter	Callback handler validates and consumes state

State Parameter Security FlowLink copied!

Environment Variable ValidationLink copied!

The endpoint validates that GITHUB_APP_SLUG is configured before proceeding app/api/auth/github/route.ts L7-L9

preventing runtime errors during redirect construction. Missing configuration returns an explicit error message rather than failing silently.

Sources: app/api/auth/github/route.ts L7-L34

Code Entity ReferenceLink copied!

Primary File: app/api/auth/github/route.ts

Key Functions and Symbols:

Symbol	Type	Purpose
`GET`	Route Handler	Main endpoint function
`GITHUB_APP_SLUG`	Environment Variable	GitHub App identifier for redirect URL
`github_oauth_state`	Cookie Name	Stores state for CSRF validation
`crypto.randomUUID()`	Web Crypto API	Generates CSRF token
`redirect()`	Next.js Function	Issues HTTP 302 redirect
`cookies()`	Next.js Function	Accesses cookie storage API

Related Files:

app/success/page.tsx L54 - Initiates OAuth flow by linking to this endpoint
app/api/auth/github/callback/route.ts - Validates state parameter set by this endpoint